<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
		<meta name="generator" content=
		"HTML Tidy for Linux/x86 (vers 25 March 2009), see www.w3.org" />

		<title>Closure Annotated Compiler Documentation</title>
		<link href='http://fonts.googleapis.com/css?family=Source+Code+Pro:300' rel=
		'stylesheet' type='text/css' />
		<link href='http://fonts.googleapis.com/css?family=Droid+Serif:400,700' rel='stylesheet' type='text/css'>
		<link href="http://fonts.googleapis.com/css?family=Droid+Sans" rel="stylesheet" type="text/css">
		
		<style type="text/css">
			/*<![CDATA[*/
			pre {
				color: blue;
				font-family: 'Source Code Pro', sans-serif;
				font-size: 12px;
				line-height: 15px;
				white-space: pre-wrap;
				white-space: -moz-pre-wrap;
				white-space: -pre-wrap;
				white-space: -o-pre-wrap;
				word-wrap: break-word;
			}
			h1 {
				font-family: 'Droid Serif', Georgia, Times, serif;
				font-weight: 700;
				font-size: 45px;
				line-height: 55px;
			}
			p {
				font-family: 'Droid Sans', Helvetica, Arial, sans-serif;
				font-size: 14px;
				line-height: 20px;
				text-overflow: wrap;
			}
			.example {
				border-style: dotted;
				border-width: 1px;
				position: relative;
				left: 50px;
			}
			.markup {
				color: red;
			}
			.comment {
				color: green;
			}
			/*]]>*/
		</style>
	</head>

	<body>
		<h1>Write maintainable webapps:</h1>
		<p>
			Webapps these days are complicated. There is lots of html, and javascript projects
			have reached a level of complixity where trying to put all your functionality into a
			single app.js file renders it unmaintainable. But webapps load, layout, and execute
			faster if they, and their associated content are minified. There are tools to <a href=
			"http://code.google.com/p/htmlcompressor/">minify your html</a>, <a href=
			"http://www.minifycss.com/">your css</a>, <a href=
			"https://developers.google.com/closure/compiler/">and compile your javascript.</a> They
			do the job, but configuring them as part of your build process can be a bit of a chore,
			and they can force you to do your development and testing in a slower, stepwise process
			of writing your code, running a handfull of tools, then testing your code.
		</p>

		<p>
			The goal of this project is to allow you to write a webpage _as if_ the number of
			includes in a page and the amount of whitespace didn't matter.
		</p>

		<ul>
			<li>
				Write your javascript with each functional unit in it's own small js file.
			</li>

			<li>
				Write your html with plenty of whitespace and comments.
			</li>

			<li>
				Maybe even include your unit tests directly in your main application page.
			</li>

			<li>
				Do all your testing and debugging with this page.
			</li>

			<li>
				Then run this compiler and get minified html with your tests and comments removed
				and your javascript compiled, minifed, and compressed into a single file.
			</li>
		</ul>

		<p>
			The closure annotated compiler allows you to configure sets of compilation tasks on
			javascript (and other web resources) by annotating the html document with html
			comments. This way you can write your web app in the most readable way possible, then
			easily compile to a faster and smaller target.
		</p>

		<h1>Quick Start:</h1>
<p>1) Check out (and copy) the examples in the tests: <a href="http://code.google.com/p/webapp-compiler/source/browse/trunk/src/test/webapp/">http://code.google.com/p/webapp-compiler/source/browse/trunk/src/test/webapp/</a></p>
<p>2) Build the tool (mvn clean package) or download it: <a href="http://webapp-compiler.googlecode.com/svn/trunk/bin/webappcompiler.jar">http://webapp-compiler.googlecode.com/svn/trunk/bin/webappcompiler.jar</a></p>
<p>3) Run it: java -jar ~/webappcompiler.jar /path/to/your/file.html </p>

		<h1>Examples:</h1>

		<h2>Basic Example:</h2>

		<div class="example">
			<pre class="comment">
&lt;!--
  @CompilePage(
    outputFile="basic-min.html"
    minify=true
  )

  @ClosureExtern(
    name=ext)
--&gt; 
</pre>
			<pre class="markup">
&lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="http://ajax.cdnjs.com/ajax/libs/json2/20110223/json2.js"&gt;&lt;/script&gt;
</pre>
			<pre class="comment">
&lt;!--
        
  @ClosureExtern_end
  
  @ClosureCompilation(
    outputFile="js/app-min.js"
    externBlocks="ext"
    compilationLevel=ADVANCED_OPTIMIZATIONS
  )
--&gt;
</pre>
			<pre class="markup">
&lt;script type="text/javascript" src="jssrc/AppController.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jssrc/model/User.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jssrc/model/Document.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jssrc/model/Message.js"&gt;&lt;/script&gt;
&lt;script type="text/javascript" src="jssrc/utilities/NetworkUtils.js"&gt;&lt;/script&gt;
</pre>
			<pre class="comment">
&lt;!--
  @ClosureCompilation_end
--&gt;
</pre>
		</div>

		<p>
			The example above will compile the second set of javascript files (Document.js,
			Message.js, etc) into a minified file called js/app-min.js (in a location relative to the
			document marked up), their script tags will be replaced with a single script tag
			referencing app-min.js It will use the first two files (jquery, and json2) as <a href=
			"https://developers.google.com/closure/compiler/docs/api-tutorial3">externs</a> for
			that compilation. Finally, the html file containing them will be minified (extranious
			space and all comments removed) and written out as writeonce-min.html.
		</p>

		<p>
			The entire block above will end up looking like this:
		</p>
		<div class="example">
			<pre class="markup">
&lt;script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/1.8.3/jquery.min.js"&gt;&lt;/script&gt;&lt;script type="text/javascript" src="http://ajax.cdnjs.com/ajax/libs/json2/20110223/json2.js"&gt;&lt;/script&gt;&lt;script type="text/javascript" src="js/app-min.js"&gt;&lt;/script&gt;
</pre>
		</div>
		<h2>Path Translation:</h2>
		<div class="example">
			<pre class="comment">
&lt;!--
  @SourcePathTranslation(
    regex="http://mycdn.com/static/"
    replacement="static_files/"
  )
--&gt;
</pre>
		</div>

		<p>
			This tag needs no _end tag (although you can put one in if you want). It tells the
			closure compiler to look in a different place for a file than what is in the src
			tag.
		</p>

		<p>
			For example, if part of your deployment involves putting files on a CDN, you may
			want to reference files on that CDN from your application's html document. This allows
			you to do that, but still allow the compiler to find the files within the local
			filesystem.
		</p>

		<h2>CopyFiles:</h2>TODO:
		<div class="example">
			<pre class="comment">
&lt;!--
        @CopyFiles(
                outputDirectory="js")
--&gt;
&lt; script type="text/javascript" src="jsext/jquery-1.8.2.js"&gt;&lt;/script&gt;
&lt; script type="text/javascript" src="jsext/json2.js"&gt;&lt;/script&gt;
&lt;!--
        @CopyFiles_end
--&gt;
</pre>
		</div>
		<h2>RemoveContent:</h2>TODO:
		<div class="example">
			<pre class="comment">
&lt;!--
        @RemoveContent 
--&gt;
&lt; script type="text/javascript" src="jsext/jquery-1.8.2.js"&gt;&lt;/script&gt;
&lt; script type="text/javascript" src="jsext/json2.js"&gt;&lt;/script&gt;
&lt;!--
        @RemoveContent_end
--&gt;
</pre>
		</div>

		<h1>Building:</h1>
			<p><i>mvn clean package</i> should do the trick.</p>
		
		<h1>"Roadmap":</h1>

		<ul>
			<li>
				Rename files (eg: for CDN deploy)
			</li>

			<li>
				CSS minification
			</li>

			<li>
				Run JSDoc with compilations
			</li>

			<li>
				Maven
			</li>

			<li>
				Eclipse
			</li>

			<li>
				Incremental compilation
			</li>

			<li>
				Push compiled assets to a CDN?
			</li>
		</ul>
	</body>
</html>